home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sources / xpick / xpick_11.z / xpick_11 / xpick-1.1 / MultiList.h < prev    next >
C/C++ Source or Header  |  1991-09-20  |  10KB  |  235 lines
  1. /****************************************************************************
  2.  
  3.     MultiList.h
  4.  
  5.     This file is the public header file for the MultiList widget, an
  6.     extension to the Athena List widget.
  7.  
  8.     This code is loosely based on the Athena List source which
  9.     is why the MIT copyright notice appears below.
  10.  
  11.     July 1990, Brian Totty
  12.  
  13.  ****************************************************************************/
  14.  
  15. /*
  16.  * Copyright 1989 Massachusetts Institute of Technology
  17.  *
  18.  * Permission to use, copy, modify, distribute, and sell this software and its
  19.  * documentation for any purpose is hereby granted without fee, provided that
  20.  * the above copyright notice appear in all copies and that both that
  21.  * copyright notice and this permission notice appear in supporting
  22.  * documentation, and that the name of M.I.T. not be used in advertising or
  23.  * publicity pertaining to distribution of the software without specific,
  24.  * written prior permission.  M.I.T. makes no representations about the
  25.  * suitability of this software for any purpose.  It is provided "as is"
  26.  * without express or implied warranty.
  27.  *
  28.  * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  29.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
  30.  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  31.  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  32.  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 
  33.  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  34.  *
  35.  * Original Athena Author:  Chris D. Peterson, MIT X Consortium
  36.  */
  37.  
  38. #ifndef _MULTILIST_H_
  39. #define _MULTILIST_H_
  40.  
  41. #include <X11/Xaw/Simple.h>
  42.  
  43. /*---------------------------------------------------------------------------*
  44.  
  45.       R E S O U R C E    D E S C R I P T I O N S    A N D    N O T E S
  46.  
  47.  *---------------------------------------------------------------------------*/
  48.  
  49. /*
  50.  
  51.  Name             Class        RepType        Default Value
  52.  ----             -----        -------        -------------
  53.  background         Background        Pixel        XtDefaultBackground
  54.  border             BorderColor    Pixel        XtDefaultForeground
  55.  borderWidth         BorderWidth    Dimension    1
  56.  callback            Callback           XtCallbackList  NULL                *1
  57.  columnWidth         Width              Dimension       0                   *10
  58.  columnSpacing       Spacing            Dimension       8
  59.  cursor             Cursor        Cursor        left_ptr
  60.  defaultColumns      Columns            int             1                   *2
  61.  destroyCallback     Callback        Pointer        NULL 
  62.  font             Font        XFontStruct*    XtDefaultFont
  63.  forceColumns        Columns            Boolean         False               *2
  64.  foreground         Foreground        Pixel        XtDefaultForeground
  65.  height             Height        Dimension    0                   *3
  66.  highlightBackground HBackground    Pixel        XtDefaultForeground *4
  67.  highlightForeground HForeground    Pixel        XtDefaultBackground *4
  68.  insensitiveBorder   Insensitive    Pixmap        Gray
  69.  list                List               String *        NULL                *5
  70.  longest             Longest            int             0                   *6
  71.  mappedWhenManaged   MappedWhenManaged    Boolean        True
  72.  maxSelectable       Value              int             1                   *7
  73.  notifyHighlights    Boolean            Boolean         True                *8
  74.  notifyOpens         Boolean            Boolean         True                *8
  75.  notifyUnhighlights  Boolean            Boolean         True                *8
  76.  numberStrings       NumberStrings      int             0                   *5
  77.  pasteBuffer         Boolean            Boolean         False
  78.  rowHeight           Height             Dimension       0                   *10
  79.  rowSpacing          Spacing            Dimension       2
  80.  sensitive         Sensitive        Boolean        True
  81.  sensitiveArray      List               Boolean *       NULL                *9
  82.  verticalList        Boolean            Boolean         False
  83.  width             Width        Dimension    0
  84.  x             Position        Position    0
  85.  y             Position        Position    0
  86.  
  87.  *1 -  The callback functions are called whenever a highlight, unhighlight,
  88.        or open takes place, and the appropriate notification resource is
  89.        set true.  The callbacks get called with a MultiListReturnStruct pointer
  90.        which points to the data about the action that just occurred.
  91.  
  92.  *2 -  The defaultColumns resource is used in two cases.  If forceColumns
  93.        is true, the widget will set the number of columns to the value of
  94.        default columns.  If the widget width is unconstrained by the parent
  95.        widgets, the defaultColumns is also used to determine the number of
  96.        columns and the resulting width.  Otherwise, the number of columns
  97.        will be calcultaed based on the current width and will be changed to
  98.        an appropriate value.
  99.  
  100.  *3 -  If the width or height is set to zero (0), which is the default case,
  101.        then the widget will calculate the size of that dimension to be just
  102.        large enough to hold the contents of the widget.
  103.  
  104.  *4 -  The highlightForeground and highlightBackground colors specify the
  105.        colors used to highlight the text (foreground) and the surrounding
  106.        background space of a list item when it is selected (highlighted).
  107.        The default is the reverse of the default foreground and background
  108.        colors.
  109.  
  110.  *5 -  The list resource is an array of strings (char * array) which tell
  111.        the names of each item of the list.  The number of elements of this
  112.        array are indicated by the resource numberStrings.  If numberStrings
  113.        is set to 0 (the default), then the MultiList widget will count the
  114.        number of strings in the list.  This requires that the list be
  115.        NULL terminated.  If list is NULL, then the widget treats it as an
  116.        empty list.  Once the list is set the list resource is set to NULL,
  117.        so you won't be able to read back the list after it has been set.  The
  118.        widgets copies the strings internally, so the user can free the list
  119.        storage after setting it.
  120.  
  121.  *6 -  This resource represent the longest string in pixels.  If this
  122.        resource is zero (0), which is the default and probably the value
  123.        most people should use, the longest string length is calculated
  124.        and the resource is updated.
  125.  
  126.  *7 -  The maxSelectable resource indicates the maximum number of items
  127.        which can be selected at any one time.  In the original Athena
  128.        widget, you could have at most one item selected at a time.  In
  129.        this widget, you can choose how many will be selected at a time.
  130.  
  131.  *8 -  When an item is highlighted or becomes unhighlighted, or when
  132.        the Open() action is run, a callback can be issued indicating the
  133.        new state of what items are highlighted and what action occurred.
  134.        The notify resources are booleans that enable or disable callbacks
  135.        in various cases.  If you are only interested in being notified
  136.        when the user selects an item, and not when he deselects items,
  137.        then only notifyHighlights needs to be True.
  138.  
  139.  *9 -  Each item in the MultiList can be made insensitive, so it is printed in
  140.        gray shading and can not be highlighted.  This can be done by
  141.        setting the sensitivity list, which is an array of Booleans which
  142.        indicate whether or not the corresponding item is sensitive (can be
  143.        selected).  If sensitivity list is NULL, all items are sensitive.  The
  144.        widget copies the sensitivity information, so the user can delete the
  145.        sensitivity array storage after setting it.  The widget sets the
  146.        resource to NULL after it has been set, so the user cannot read the
  147.        old list back.
  148.  
  149.  *10 - These values are intended for reading only.  They indicate the pixel
  150.        width/height of the column/row.
  151.  
  152. */
  153.  
  154. /*---------------------------------------------------------------------------*
  155.  
  156.                     S T R I N G    D E F I N I T I O N S
  157.  
  158.  *---------------------------------------------------------------------------*/
  159.  
  160. #define XtCList            "List"
  161. #define XtCSpacing        "Spacing"
  162. #define XtCColumns        "Columns"
  163. #define XtCLongest        "Longest"
  164. #define XtCNumberStrings    "NumberStrings"
  165. #define    XtCHForeground        "HForeground"
  166. #define    XtCHBackground        "HBackground"
  167.  
  168. #ifndef XtNcursor
  169. #define XtNcursor        "cursor"
  170. #endif
  171.  
  172. #define    XtNhighlightForeground    "highlightForeground"
  173. #define    XtNhighlightBackground    "highlightBackground"
  174. #define XtNcolumnSpacing    "columnSpacing"
  175. #define XtNrowSpacing        "rowSpacing"
  176. #define XtNdefaultColumns    "defaultColumns"
  177. #define XtNforceColumns        "forceColumns"
  178. #define XtNpasteBuffer        "pasteBuffer"
  179. #define XtNverticalList        "verticalList"
  180. #define XtNlongest        "longest"
  181. #define XtNnumberStrings    "numberStrings"
  182. #define XtNlist            "list"
  183. #define    XtNsensitiveArray    "sensitiveArray"
  184. #define    XtNmaxSelectable    "maxSelectable"
  185. #define    XtNnotifyHighlights    "notifyHighlights"
  186. #define    XtNnotifyUnhighlights    "notifyUnhighlights"
  187. #define    XtNnotifyOpens        "notifyOpens"
  188.  
  189. #define    XtNrowHeight        "rowHeight"
  190. #define    XtNcolumnWidth        "columnWidth"
  191.  
  192.     /* Class Record Constants */
  193.  
  194. extern WidgetClass multiListWidgetClass;
  195.  
  196. typedef struct _MultiListClassRec *MultiListWidgetClass;
  197. typedef struct _MultiListRec      *MultiListWidget;
  198.  
  199. /*---------------------------------------------------------------------------*
  200.  
  201.                      R E T U R N    S T R U C T U R E
  202.  
  203.  *---------------------------------------------------------------------------*/
  204.  
  205. #define    MULTILIST_ACTION_HIGHLIGHT        0
  206. #define    MULTILIST_ACTION_UNHIGHLIGHT        1
  207. #define    MULTILIST_ACTION_OPEN            2
  208. #define    MULTILIST_ACTION_STATUS            3
  209.  
  210. typedef struct _MultiListReturnStruct
  211. {
  212.     int action;
  213.     int item;
  214.     String string;
  215.     int num_selected;
  216.     int *selected_items;
  217. } MultiListReturnStruct;
  218.  
  219. /*---------------------------------------------------------------------------*
  220.  
  221.                      U T I L I T Y    R O U T I N E S
  222.  
  223.  *---------------------------------------------------------------------------*/
  224.  
  225. void                MultiListHighlightItem();
  226. void                MultiListHighlightAll();
  227. void                MultiListUnhighlightItem();
  228. void                 MultiListUnhighlightAll();
  229. int                 MultiListToggleItem();
  230. Boolean                MultiListIsHighlighted();
  231. Boolean                MultiListGetItemInfo();
  232. MultiListReturnStruct        *MultiListGetHighlighted();
  233.  
  234. #endif
  235.